---
title: Installation | gluestack-ui-v2

description: To get started with gluestack-ui v2, check out this quick installation guide. It provides simple steps to help you install and use the library in your projects.

pageTitle: Installation

pageDescription: To get started with gluestack-ui v2, check out this quick installation guide. It provides simple steps to help you install and use the library in your projects.

showHeader: false
---

import { Meta } from '@storybook/addon-docs';
import { CollapsibleCode, Tabs } from '@gluestack/design-system';

<Meta title="with-nativewind/Home/Getting Started/Installation" />

# Installation

To get started with **gluestack-ui v2**, check out this quick installation guide. It provides simple steps to help you install and use the library in your projects.

<br />

<Tabs value="cli" type="section">
<Tabs.TabList>
      <Tabs.Tab value="cli">
        <Tabs.TabTitle>CLI</Tabs.TabTitle>
      </Tabs.Tab>
     <Tabs.Tab value="manual">
        <Tabs.TabTitle>Manual</Tabs.TabTitle>
     </Tabs.Tab>
  </Tabs.TabList>
  <Tabs.TabPanels>
    <Tabs.TabPanel value="cli">
<>

<br />

### Step 1: Setup your project

If you are starting with a new project, setup your project with [Next.js](https://nextjs.org/docs/getting-started/installation) or [Expo](https://docs.expo.dev/get-started/create-a-project/). If you already have a project, you can skip this step.

### Prerequisites
Ensure you have the following prerequisites installed on your project to use gluestack-ui CLI:

- Node.js: Version 16 or higher.
- React: Version 18 or higher.

### Step 2: Initialize

Go to your project, and use the `init` command at the root of your project to add `GluestackUIProvider` and the `gluestack-ui-provider/config.ts` file to your project..

```bash
npx gluestack-ui init
```

> Installation using gluestack-ui CLI in Expo projects supports for Expo SDK 50 and above only. For Expo SDK < 49, please refer to the manual installation.

Your project is now ready to use **gluestack-ui** components. To add gluestack-ui components to your project using the CLI, refer to the above command or use the [CLI guide](/ui/docs/home/getting-started/cli).

```bash
npx gluestack-ui add box
```

If you encounter issues during the CLI installation, refer to the manual installation guide available.

</>
    </Tabs.TabPanel>
    <Tabs.TabPanel value="manual"> 
<>
<br />

### Step 1: Setup your project.

Setup nativewind in your project following [NativeWind documentation](https://www.nativewind.dev/v4/getting-started/react-native).

### Step 2: Install dependencies

Install the dependencies of gluestack-ui in your project. This can be done using the following command:

```bash
yarn add @gluestack-ui/nativewind-utils

```

OR

```bash
npm i @gluestack-ui/nativewind-utils

```

### Step 2.1: Update Tailwind configuration

Update `tailwind.config.js` file with the following code

```js
%%-- File: tailwind.config.js --%% 
```

### Step 2.2: Configure components path

Create a `components/ui` folder inside `src` folder and add path in `tsconfig.json`

```js
  // ... (other configs)
  compilerOptions: {
    // ...
    "paths": {
      // ...
      "@/*": ["./src/*"] // Add relative path
    },
  }
```

### Step 2.3: Configure GluestackUIProvider

To add config, create a `gluestack-ui-provider/config.ts` file in your `components/ui` folder and paste the following code.

<CollapsibleCode>

```jsx
%%-- File: core-components/nativewind/gluestack-ui-provider/config.ts --%%
```

</CollapsibleCode>

#### For Native
To add `GluestackUIProvider`, create a `gluestack-ui-provider/index.tsx` file inside `components/` folder and paste the following code.

<CollapsibleCode>

```jsx
%%-- File: core-components/nativewind/gluestack-ui-provider/index.tsx --%%
```

</CollapsibleCode>

#### For Web
To add `GluestackUIProvider`, create a `gluestack-ui-provider/index.web.tsx` file inside `components/` folder and paste the following code.

<CollapsibleCode>

```jsx
%%-- File: core-components/nativewind/gluestack-ui-provider/index.web.tsx --%%
```

</CollapsibleCode>

### Step 3: Configure GluestackUIProvider in project

Wrap your app with `GluestackUIProvider` in `App.tsx`.

```jsx
// App.tsx
export default function App() {
  return (
    <GluestackUIProvider>{/* Add your app code here */}</GluestackUIProvider>
  );
}
```

### Step 4: Server-side rendering (SSR) (Next.js Only).

It's also recommended to set up your server-side rendering (SSR) correctly. To do this, you will need to use the `flush()` function exported by the `@gluestack-ui/nativewind-utils`

<Tabs value="App Router" type="section">
<Tabs.TabList>
  <Tabs.Tab value="App Router">
    <Tabs.TabTitle>App Router</Tabs.TabTitle>
  </Tabs.Tab>
  <Tabs.Tab value="Page Router">
      <Tabs.TabTitle>Page Router</Tabs.TabTitle>
  </Tabs.Tab>
  </Tabs.TabList>
  <Tabs.TabPanels>
    <Tabs.TabPanel value="App Router">
<>
<br/>

For Next.js App Routers we will create a new `registry.tsx` file in the root of your project and use the flush function from `@gluestack-ui/nativewind-utils`

```jsx
"use client";

import React, { useRef, useState } from "react";
import { useServerInsertedHTML } from "next/navigation";
import { StyleRegistry, createStyleRegistry } from "styled-jsx";
import { Html, Head, Main, NextScript } from "next/document";
// @ts-ignore
import { AppRegistry } from "react-native-web";
import { flush } from "@gluestack-ui/nativewind-utils/flush";

export default function StyledJsxRegistry({
  children,
}: {
  children: React.ReactNode;
}) {
  // Only create stylesheet once with lazy initial state
  // x-ref: https://reactjs.org/docs/hooks-reference.html#lazy-initial-state
  const [jsxStyleRegistry] = useState(() => createStyleRegistry());
  const isServerInserted = useRef(false);

  useServerInsertedHTML(() => {
    AppRegistry.registerComponent("Main", () => Main);
    const { getStyleElement } = AppRegistry.getApplication("Main");
    console.log(getStyleElement());
    if (!isServerInserted.current) {
      isServerInserted.current = true;
      const styles = [
        getStyleElement(),
        jsxStyleRegistry.styles(),
        flush(),
      ];
      jsxStyleRegistry.flush();
      return <>{styles}</>;
    }
  });

  return <StyleRegistry registry={jsxStyleRegistry}>{children}</StyleRegistry>;
}

```

- We also need to wrap `children` with `StyledJsxRegistry` in the `layout.tsx` file.

```jsx
"use client";

import { Inter } from "next/font/google";
import "./globals.css";
import { GluestackUIProvider } from "@/components/ui/gluestack-ui-provider";
const inter = Inter({ subsets: ["latin"] });
import StyledJsxRegistry from "./registry";
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className} style={{ display: "flex" }}>
        <StyledJsxRegistry>
          <GluestackUIProvider mode="light">{children}</GluestackUIProvider>
        </StyledJsxRegistry>
      </body>
    </html>
  );
}

```

</>
    </Tabs.TabPanel>
    <Tabs.TabPanel value="Page Router">
<>
<br/>


For Next.js we will add this code in `_document.tsx` file.

```jsx
import * as React from 'react';
import { Html, Head, Main, NextScript } from 'next/document';
import { AppRegistry } from 'react-native-web';
import { flush } from '@gluestack-ui/nativewind-utils/flush';

function Document() {
  return (
    <Html className="gs" lang="en">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Document.getInitialProps = async ({ renderPage }: any) => {
  AppRegistry.registerComponent('Main', () => Main);
  const { getStyleElement } = AppRegistry.getApplication('Main');
  const page = await renderPage();
  const styles = [getStyleElement(), flush()];
  return { ...page, styles: React.Children.toArray(styles) };
};

export default Document;
```

</>
    </Tabs.TabPanel>
  </Tabs.TabPanels>
</Tabs>

</>
    </Tabs.TabPanel>
  </Tabs.TabPanels>
</Tabs>

## Common issues
**Expo app stuck in `tailwindcss(ios) rebuilding...` while running `expo start` command**

In this case, you may have your app stored in a directory with a name containing spaces, such as 'Expo App', renaming it to just 'Expo-App' will resolve the issue.
